+2007-07-01 Matthias Clasen <mclasen@redhat.com>
+
+ * gtk/tmpl/*.sgml: Document GtkBuilder ui definitions.
+
2007-07-01 Johan Dahlin <jdahlin@async.com.br>
* gtk/gtk-builder-convert.xml: Updates
</para>
-<!-- ##### ARG GtkFileChooser:action ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
-<para>
-
-</para>
-
-
<!-- ##### ARG GtkFileChooser:file-system ##### -->
<para>
</para>
-<!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:filter ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:local-only ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
-<para>
-
-</para>
-
-
<!-- ##### ENUM GtkFontFilterType ##### -->
<para>
A set of bit flags used to specify the filter being set
</para>
-<!-- ##### ARG GtkRecentChooser:filter ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:limit ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:local-only ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:recent-manager ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:select-multiple ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-icons ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-not-found ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-private ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:show-tips ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkRecentChooser:sort-type ##### -->
-<para>
-
-</para>
-
-
<!-- ##### ARG GtkScrolledWindow:shadow ##### -->
<para>
sure that the correct shortcut is displayed next to the menu item.
</para>
+<refsect2 id="GtkActionGroup-BUILDER-UI">
+<title>GtkActionGroup as GtkBuildable</title>
+<para>
+The GtkActionGroup implementation of the GtkBuildable interface accepts
+GtkAction objects as <child> elements in UI definitions.
+</para>
+<para>
+Note that it is probably more common to define actions and action groups
+in the code, since they are directly related to what the code can do.
+</para>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<para>
Beyond this general structure, several object classes define
their own XML DTD fragments for filling in the ANY placeholders.
-See
+These are explained in their own sections, see
+<link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
+<link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,
+<link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>,
+<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>,
+<link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>,
+<link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>,
+<link linkend="GtkComboBoxEntry-BUILDER-UI">GtkComboBoxEntry</link>,
+<link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>,
+<link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>,
+<link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>,
+<link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>,
+<link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>,
+<link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>,
+<link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>,
+<link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>,
+<link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>.
</para>
-<simplelist>
- <member><link linkend="GtkDialog-BUILDER-UI">GtkDialog as GtkBuildable</link></member>
-</simplelist>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
of the attribute for each cell that is rendered.
</para>
+<refsect2 id="GtkCellLayout-BUILDER-UI">
+<title>GtkCellLayouts as GtkBuildable</title>
+<para>
+Implementations of GtkCellLayout which also implement the GtkBuildable
+interface (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkComboBoxEntry,
+#GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer objects
+as <child> elements in UI definitons. They support a custom
+<attributes> element for their children, which can contain
+multiple <attribute> elements. Each <attribute> element has
+a name attribute which specifies a property of the cell renderer; the
+content of the element is the attribute value.
+</para>
+<example>
+<title>A UI definition fragment specifying attributes</title>
+<programlisting><![CDATA[
+<object class="GtkCellView">
+ <child>
+ <object class="GtkCellRendererText"/>
+ <attributes>
+ <attribute name="text">0</attribute>
+ </attributes>
+ </child>"
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
provides a standard dialog for file selection.
</para>
+<refsect2 id="GtkColorSelectionDialog-BUILDER-UI">
+<title>GtkColorSelectionDialog as GtkBuildable</title>
+<para>
+The GtkColorSelectionDialog implementation of the GtkBuildable interface
+exposes the embedded #GtkColorSelection as internal child with the
+name "color_selection". It also exposes the buttons with the names
+"ok_button", "cancel_button" and "help_button".
+</para>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
gtk_container_remove() and gtk_container_add().
</para>
+<refsect2 id="GtkComboBoxEntry-BUILDER-UI">
+<title>GtkComboBoxEntry as GtkBuildable</title>
+<para>
+Beyond the <attributes> support that is shared by all
+<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link> implementation,
+GtkComboBoxEntry makes the entry available in UI definitions as an internal
+child with name "entry".
+</para>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkComboBox
<!-- ##### SECTION Long_Description ##### -->
<para>
-A GTK+ user interface is constructed by nesting widgets inside widgets. Container widgets are the inner
-nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a
-#GtkWindow containing a #GtkFrame containing a GtkLabel. If you wanted an image instead of a textual label
-inside the frame, you might replace the #GtkLabel widget with a #GtkImage widget.
+A GTK+ user interface is constructed by nesting widgets inside widgets.
+Container widgets are the inner nodes in the resulting tree of widgets:
+they contain other widgets. So, for example, you might have a #GtkWindow
+containing a #GtkFrame containing a GtkLabel. If you wanted an image instead
+of a textual label inside the frame, you might replace the #GtkLabel widget
+with a #GtkImage widget.
</para>
<para>
-There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract #GtkContainer
-base class.
+There are two major kinds of container widgets in GTK+. Both are subclasses
+of the abstract #GtkContainer base class.
</para>
<para>
-The first type of container widget has a single child widget and derives from #GtkBin. These containers
-are <firstterm>decorators</firstterm>, which add some kind of functionality to the child. For example,
-a #GtkButton makes its child into a clickable button; a #GtkFrame draws a frame around its child and
-a #GtkWindow places its child widget inside a top-level window.
+The first type of container widget has a single child widget and derives
+from #GtkBin. These containers are <firstterm>decorators</firstterm>, which
+add some kind of functionality to the child. For example, a #GtkButton makes
+its child into a clickable button; a #GtkFrame draws a frame around its child
+and a #GtkWindow places its child widget inside a top-level window.
</para>
<para>
-The second type of container can have more than one child; its purpose is to manage
-<firstterm>layout</firstterm>. This means that these containers assign sizes and positions to their children.
-For example, a #GtkHBox arranges its children in a horizontal row, and a #GtkTable arranges the widgets it
-contains in a two-dimensional grid.
+The second type of container can have more than one child; its purpose is to
+manage <firstterm>layout</firstterm>. This means that these containers assign
+sizes and positions to their children. For example, a #GtkHBox arranges its
+children in a horizontal row, and a #GtkTable arranges the widgets it contains
+in a two-dimensional grid.
</para>
<para>
-To fulfill its task, a layout container must negotiate the size requirements with its parent and its children.
-This negotiation is carried out in two phases, <firstterm>size requisition</firstterm> and
-<firstterm>size allocation</firstterm>.
+To fulfill its task, a layout container must negotiate the size requirements
+with its parent and its children. This negotiation is carried out in two
+phases, <firstterm>size requisition</firstterm> and <firstterm>size
+allocation</firstterm>.
</para>
<refsect2 id="size-requisition"><title>Size Requisition</title>
<para>
-The size requisition of a widget is it's desired width and height. This is represented by a #GtkRequisition.
+The size requisition of a widget is it's desired width and height.
+This is represented by a #GtkRequisition.
</para>
<para>
-How a widget determines its desired size depends on the widget. A #GtkLabel, for example, requests enough space
-to display all its text. Container widgets generally base their size request on the requisitions of their
-children.
+How a widget determines its desired size depends on the widget.
+A #GtkLabel, for example, requests enough space to display all its text.
+Container widgets generally base their size request on the requisitions
+of their children.
</para>
<para>
-The size requisition phase of the widget layout process operates top-down. It starts at a top-level widget,
-typically a #GtkWindow. The top-level widget asks its child for its size requisition by calling
-gtk_widget_size_request(). To determine its requisition, the child asks its own children for their requisitions
-and so on. Finally, the top-level widget will get a requisition back from its child.
+The size requisition phase of the widget layout process operates top-down.
+It starts at a top-level widget, typically a #GtkWindow. The top-level widget
+asks its child for its size requisition by calling gtk_widget_size_request().
+To determine its requisition, the child asks its own children for their
+requisitions and so on. Finally, the top-level widget will get a requisition
+back from its child.
</para>
</refsect2>
<refsect2 id="size-allocation"><title>Size Allocation</title>
<para>
-When the top-level widget has determined how much space its child would like to have, the second phase of the
-size negotiation, size allocation, begins. Depending on its configuration (see gtk_window_set_resizable()), the
-top-level widget may be able to expand in order to satisfy the size request or it may have to ignore the size
-request and keep its fixed size. It then tells its child widget how much space it gets by calling
-gtk_widget_size_allocate(). The child widget divides the space among its children and tells each child how much
-space it got, and so on. Under normal circumstances, a #GtkWindow will always give its child the amount of space
-the child requested.
+When the top-level widget has determined how much space its child would like
+to have, the second phase of the size negotiation, size allocation, begins.
+Depending on its configuration (see gtk_window_set_resizable()), the top-level
+widget may be able to expand in order to satisfy the size request or it may
+have to ignore the size request and keep its fixed size. It then tells its
+child widget how much space it gets by calling gtk_widget_size_allocate().
+The child widget divides the space among its children and tells each child
+how much space it got, and so on. Under normal circumstances, a #GtkWindow
+will always give its child the amount of space the child requested.
</para>
<para>
-A child's size allocation is represented by a #GtkAllocation. This struct contains not only a width and height,
-but also a position (i.e. X and Y coordinates), so that containers can tell their children not only how much
-space they have gotten, but also where they are positioned inside the space available to the container.
+A child's size allocation is represented by a #GtkAllocation. This struct
+contains not only a width and height, but also a position (i.e. X and Y
+coordinates), so that containers can tell their children not only how much
+space they have gotten, but also where they are positioned inside the space
+available to the container.
</para>
<para>
-Widgets are required to honor the size allocation they receive; a size request is only a request, and widgets
-must be able to cope with any size.
+Widgets are required to honor the size allocation they receive; a size
+request is only a request, and widgets must be able to cope with any size.
</para>
</refsect2>
<refsect2 id="child-properties"><title>Child properties</title>
</para>
</refsect2>
+<refsect2 id="GtkContainer-BUILDER-UI">
+<title>GtkContainer as GtkBuildable</title>
+<para>
+The GtkContainer implementation of the GtkBuildable interface
+supports a <packing> element for children, which can
+contain multiple <property> elements that specify
+child properties for the child.
+</para>
+<example>
+<title>Child properties in UI definitions</title>
+<programlisting><![CDATA[
+<object class="GtkVBox">
+ <child>
+ <object class="GtkLabel"/>
+ <packing>
+ <property name="pack-type">start</property>
+ </packing>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
</example>
</para>
-<refsect2><title>GtkDialog as a GtkBuildable</title>
+<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
<para>
-GtkDialog exposes the @vbox and @action_area as internal children
-with the names "vbox" and "action_area".
+The GtkDialog implementation of the GtkBuildable interface exposes the
+@vbox and @action_area as internal children with the names "vbox" and
+"action_area".
</para>
<para>
GtkDialog supports a custom <action-widgets> element, which
<!-- ##### SECTION Long_Description ##### -->
<para>
-A #GtkExpander allows the user to hide or show its child by clicking on an expander triangle similar to
-the triangles used in a #GtkTreeView.
-</para>
-
- <para>
- Normally you use an expander as you would use any other descendant
- of #GtkBin; you create the child widget and use
- gtk_container_add() to add it to the expander. When the expander
- is toggled, it will take care of showing and hiding the child
- automatically.
- </para>
-
- <section id="expander-special-usage">
- <title>Special Usage</title>
-
- <para>
- There are situations in which you may prefer to show and
- hide the expanded widget yourself, such as when you want to
- actually create the widget at expansion time. In this case,
- create a #GtkExpander but do not add a child to it. The
- expander widget has an <literal>expanded</literal> property
- which can be used to monitor its expansion state. You should
- watch this property with a signal connection as follows:
- </para>
-
- <programlisting id="expander-callback-example">
+A #GtkExpander allows the user to hide or show its child by clicking
+on an expander triangle similar to the triangles used in a #GtkTreeView.
+</para>
+
+<para>
+Normally you use an expander as you would use any other descendant
+of #GtkBin; you create the child widget and use gtk_container_add()
+to add it to the expander. When the expander is toggled, it will take
+care of showing and hiding the child automatically.
+</para>
+
+<section id="expander-special-usage">
+<title>Special Usage</title>
+
+<para>
+There are situations in which you may prefer to show and hide the
+expanded widget yourself, such as when you want to actually create
+the widget at expansion time. In this case, create a #GtkExpander
+but do not add a child to it. The expander widget has an
+<literal>expanded</literal> property which can be used to monitor
+its expansion state. You should watch this property with a signal
+connection as follows:
+</para>
+
+<programlisting id="expander-callback-example">
expander = gtk_expander_new_with_mnemonic ("_More Options");
g_signal_connect (expander, "notify::expanded",
G_CALLBACK (expander_callback), NULL);
/* Hide or destroy widgets */
}
}
-
- </programlisting>
- </section>
+</programlisting>
+</section>
+<refsect2 id="GtkExpander-BUILDER-UI">
+<title>GtkExpander as GtkBuildable</title>
+<para>
+The GtkExpander implementation of the GtkBuildable interface
+supports placing a child in the label position by specifying
+"label" as the "type" attribute of a <child> element.
+</para>
+<example>
+<title>A UI definition fragment with GtkExpander</title>
+<programlisting><![CDATA[
+<object class="GtkExpander">
+ <child type="label">
+ <object class="GtkLabel" id="expander-label"/>
+ </child>
+ <child>
+ <object class="GtkEntry" id="expander-content"/>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
@filechooser: the object which received the signal.
+<!-- ##### ARG GtkFileChooser:action ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:do-overwrite-confirmation ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:filter ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:local-only ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkFileChooser:use-preview-label ##### -->
+<para>
+
+</para>
+
<!-- ##### ENUM GtkFileChooserAction ##### -->
<para>
Describes whether a #GtkFileChooser is being used to open
gtk_font_selection_dialog_set_preview_text().
</para>
+<refsect2 id="GtkFontSelectionDialog-BUILDER-UI">
+<title>GtkFontSelectionDialog as GtkBuildable</title>
+<para>
+The GtkFontSelectionDialog implementation of the GtkBuildable interface
+exposes the embedded #GtkFontSelection as internal child with the
+name "font_selection". It also exposes the buttons with the names
+"ok_button", "cancel_button" and "apply_button".
+</para>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
label can be controlled with gtk_frame_set_label_align().
</para>
+<refsect2 id="GtkFrame-BUILDER-UI">
+<title>GtkFrame as GtkBuildable</title>
+<para>
+The GtkFrame implementation of the GtkBuildable interface
+supports placing a child in the label position by specifying
+"label" as the "type" attribute of a <child> element.
+</para>
+<example>
+<title>A UI definition fragment with GtkFrame</title>
+<programlisting><![CDATA[
+<object class="GtkFrame">
+ <child type="label">
+ <object class="GtkLabel" id="frame-label"/>
+ </child>
+ <child>
+ <object class="GtkEntry" id="frame-content"/>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
+
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<title>Atomic Operations</title>
<para>
-It is important to note that only the methods @gtk_list_store_insert_with_values and
-@gtk_list_store_insert_with_valuesv are atomic, in the sense that the row is being appended
-to the store and the values filled in in a single operation with regard to #GtkTreeModel signaling.
-In contrast, using e.g. @gtk_list_store_append and then @gtk_list_store_set will first create a row,
-which triggers the "row_inserted" #GtkTreeModel signal on #GtkListStore. The row, however, is still
-empty, and any signal handler connecting to "row_inserted" on this particular store should be prepared
-for the situation that the row might be empty.
-This is especially important if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are
-using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore
-will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that.
+It is important to note that only the methods
+gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv()
+are atomic, in the sense that the row is being appended to the store and the
+values filled in in a single operation with regard to #GtkTreeModel signaling.
+In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set()
+will first create a row, which triggers the #GtkTreeModel::row-inserted signal
+on #GtkListStore. The row, however, is still empty, and any signal handler
+connecting to "row-inserted" on this particular store should be prepared
+for the situation that the row might be empty. This is especially important
+if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are
+using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations
+to append rows to the #GtkListStore will cause the
+#GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the
+function must be prepared for that.
</para>
</refsect2>
+<refsect2 id="GtkListStore-BUILDER-UI">
+<title>GtkListStore as GtkBuildable</title>
+<para>
+The GtkListStore implementation of the GtkBuildable interface allows
+to specify the model columns with a <columns> element that may
+contain multiple <column> elements, each specifying one model
+column. The "type" attribute specifies the data type for the column.
+</para>
+<para>
+Additionally, it is possible to specify content for the list store
+in the UI definition, with the <data> element. It can contain
+multiple <row> elements, each specifying to content for one
+row of the list model. Inside a <row>, the <col> elements
+specify the content for individual cells.
+</para>
+<para>
+Note that it is probably more common to define your models
+in the code, and one might consider it a layering violation
+to specify the content of a list store in a UI definition,
+<emphasis>data</emphasis>, not <emphasis>presentation</emphasis>,
+and common wisdom is to separate the two, as far as possible.
+<!-- FIXME a bit inconclusive -->
+</para>
+<example>
+<title>A UI Definition fragment for a list store</title>
+<programlisting><![CDATA[
+<object class="GtkListStore">
+ <columns>
+ <column type="gchararray"/>
+ <column type="gchararray"/>
+ <column type="gint"/>
+ </columns>
+ <data>
+ <row>
+ <col id="0">John</col>
+ <col id="1">Doe</col>
+ <col id="2">25</col>
+ </row>
+ <row>
+ <col id="0">Johan</col>
+ <col id="1">Dahlin</col>
+ <col id="2">50</col>
+ </row>
+ </data>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
@attach_widget: the #GtkWidget that the menu is being detached from.
-
@menu: the #GtkMenu being detached.
(see gtk_notebook_enable_popup(), gtk_noteobook_disable_popup())
</para>
+<refsect2 id="GtkNotebook-BUILDER-UI">
+<title>GtkNotebook as GtkBuildable</title>
+<para>
+The GtkNoteboopk implementation of the GtkBuildable interface
+supports placing children into tabs by specifying "tab" as the
+"type" attribbute of a <child> element. Note that the content
+of the tab must be created before the tab can be filled.
+</para>
+<example>
+<title>A UI definition fragment with GtkNotebook</title>
+<programlisting><![CDATA[
+<object class="GtkNotebook">
+ <child>
+ <object class="GtkLabel" id="notebook-content">
+ <property name="label">Content</property>
+ </object>
+ </child>
+ <child type="tab">
+ <object class="GtkLabel" id="notebook-tab">
+ <property name="label">Tab</property>
+ </object>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkContainer</term>
-<listitem><para>For functions that apply to every #GtkContainer
-(like #GtkList).</para></listitem>
+<listitem><para>For functions that apply to every #GtkContainer</para></listitem>
</varlistentry>
</variablelist>
</para>
with gtk_radio_button_new(), a widget should be packed into the radio button.
</para>
-@group: an existing #GtkRadioButton.
+@radio_group_member:
@Returns: a new radio button.
+<!-- # Unused Parameters # -->
+@group: an existing #GtkRadioButton.
<!-- ##### FUNCTION gtk_radio_button_new_with_label ##### -->
as @group.
</para>
-@group: an existing #GtkRadioButton.
+@radio_group_member:
@label: a text string to display next to the radio button.
@Returns: a new radio button.
+<!-- # Unused Parameters # -->
+@group: an existing #GtkRadioButton.
<!-- ##### FUNCTION gtk_radio_button_new_with_mnemonic ##### -->
</para>
-@group:
+@radio_group_member:
@label:
@Returns:
@recentchooser: the object which received the signal.
+<!-- ##### ARG GtkRecentChooser:filter ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:limit ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:local-only ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:recent-manager ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:select-multiple ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-icons ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-not-found ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-private ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:show-tips ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkRecentChooser:sort-type ##### -->
+<para>
+
+</para>
+
<!-- ##### STRUCT GtkRecentChooserIface ##### -->
<para>
is tailored for this use case.
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
reached from the widget by a chain of size groups of type
%GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH.
</para>
+<refsect2 id="GtkSizeGroup-BUILDER-UI">
+<title>GtkSizeGroup as GtkBuildable</title>
+<para>
+Size groups can be specified in a UI definition by placing an
+<object> element with <literal>class="GtkSizeGroup"</literal>
+somewhere in the UI definition. The widgets that belong to the
+size group are specified by a <widgets> element that may
+contain multiple <widget> elements, one for each member
+of the size group. The name attribute gives the id of the widget.
+</para>
+<example>
+<title>A UI definition fragment with GtkSizeGroup</title>
+<programlisting><![CDATA[
+<object class="GtkSizeGroup">
+ <property name="mode">GTK_SIZE_GROUP_HORIZONTAL</property>
+ <widgets>
+ <widget name="radio1"/>
+ <widget name="radio2"/>
+ </widgets>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
</example>
</para>
+<refsect2 id="GtkTreeModel-BUILDER-UI">
+<title>GtkTreeModel as GtkBuildable</title>
+<para>
+The GtkTreeStore implementation of the GtkBuildable interface allows
+to specify the model columns with a <columns> element that may
+contain multiple <column> elements, each specifying one model
+column. The "type" attribute specifies the data type for the column.
+</para>
+<example>
+<title>A UI definition fragment with GtkTreeStore</title>
+<programlisting><![CDATA[
+<object class="GtkTreeStore">
+ <columns>
+ <column type="gchararray"/>
+ <column type="guint"/>
+ </columns>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkTreeView, #GtkTreeStore, #GtkListStore, <link linkend="gtk-GtkTreeView-drag-and-drop">GtkTreeDnd</link>, #GtkTreeSortable
#GtkTreeSortable interface so it can be sorted by the view. Finally,
it also implements the tree <link linkend="gtktreednd">drag and
drop</link> interfaces.
+</para>
+<refsect2 id="GtkTreeStore-BUILDER-UI">
+<title>GtkTreeStore as GtkBuildable</title>
+<para>
+The GtkTreeStore implementation of the GtkBuildable interface allows
+to specify the model columns with a <columns> element that may
+contain multiple <column> elements, each specifying one model
+column. The "type" attribute specifies the data type for the column.
</para>
+<example>
+<title>A UI Definition fragment for a tree store</title>
+<programlisting><![CDATA[
+<object class="GtkTreeStore">
+ <columns>
+ <column type="gchararray"/>
+ <column type="gchararray"/>
+ <column type="gint"/>
+ </columns>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
(and vice versa).
</para>
+<refsect2 id="GtkTreeView-BUILDER-UI">
+<title>GtkTreeView as GtkBuildable</title>
+<para>
+The GtkTreeView implementation of the GtkBuildable interface accepts
+GtkTreeViewColumn objects as <child> elements in UI definitions.
+</para>
+<example>
+<title>A UI definition fragment with GtkTreeView</title>
+<programlisting><![CDATA[
+<object class="GtkTreeView">
+ <property name="model">liststore1</property>
+ <child>
+ <object class="GtkTreeViewColumn">
+ <property name="title">Test</property>
+ <child>
+ <object class="GtkCellRendererText"/>
+ <attributes>"
+ <attribute name="text">1</attribute>
+ </attributes>
+ </child>
+ </object>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkTreeViewColumn, #GtkTreeSelection, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle
</para>
</refsect2>
+<refsect2 id="GtkUIManager-BUILDER-UI">
+<title>GtkUIManager as GtkBuildable</title>
+<para>
+The GtkUIManager implementation of the GtkBuildable interface accepts
+GtkActionGroup objects as <child> elements in UI definitions.
+</para>
+<para>
+A GtkUIManager UI definition as described above can be embedded in
+an GtkUIManager <object> element in a GtkBuilder UI definition.
+</para>
+<para>
+The widgets that are constructed by a GtkUIManager can be embedded in
+other parts of the constructed user interface with the help of the
+"constructor" attribute. See the example below.
+</para>
+<example>
+<title>An embedded GtkUIManager UI definition</title>
+<programlisting><![CDATA[
+<object class="GtkUIManager" id="uiman">
+ <child>
+ <object class="GtkActionGroup">
+ <child>
+ <object class="GtkAction" id="file">
+ <property name="label">_File</property>
+ </object>
+ </child>
+ </object>
+ </child>
+ <ui>
+ <menubar name="menubar1">
+ <menu action="file">
+ </menu>
+ </menubar>
+ </ui>
+</object>
+<object class="GtkWindow" id="main-window">
+ <child>
+ <object class="GtkMenuBar" id="menubar1" constructor="uiman"/>
+ </child>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkBuilder
GtkVScrollbar
<!-- ##### SECTION Short_Description ##### -->
-A vertical scrollbar
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-The #GtkVScrollbar widget is a widget arranged vertically creating a
-scrollbar. See #GtkScrollbar for details on scrollbars. #GtkAdjustment
-pointers may be added to handle the adjustment of the scrollbar or it
-may be left %NULL in which case one will be created for you. See
-#GtkAdjustment for details.
+
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#GtkScrollbar, #GtkScrolledWindow
+
</para>
gtk_widget_style_get_valist() to obtain the value of a style property.
</para>
+<refsect2 id="GtkWidget-BUILDER-UI">
+<title>GtkWidget as GtkBuildable</title>
+<para>
+The GtkWidget implementation of the GtkBuildable interface supports a
+custom <accelerator> element, which has attributes named key,
+modifiers and signal and allows to specify accelerators.
+</para>
+<example>
+<title>A UI definition fragment specifying an accelerator</title>
+<programlisting><![CDATA[
+<object class="GtkButton">
+ <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
projects / gtk4.git / commitdiff